Спринт 2/18 → Тема 5/6: Требования к коду → Урок 6/7

Docstring: документирование кода

В коде уроков и заданий вы постоянно встречаете комментарии — подсказки или пояснения к коду. Строки комментариев не обрабатываются в Python и предназначены исключительно для разработчика.

Требования к оформлению комментариев таковы:

начинайте комментарий со знака #;
первое слово пишите с заглавной буквы;
следите за длиной строки — она должна быть не больше 72 символов;
заканчивайте комментарий точкой.

Комментировать каждую строчку кода считается плохим тоном. Используйте комментарии, когда нужно:

указать на участок кода, на который стоит обратить внимание;
пояснить сложные алгоритмы или логику;
указать на код, который нужно доработать;
указать на код, который хочется позже разобрать.

Есть ещё один способ пояснить свой код. Лучше один раз увидеть, чем сто раз услышать, как это делается, поэтому — к примеру.

В виртуальное окружение вашего учебного проекта установлен пакет Asciimatics. Тот самый, который отвечает за анимацию. В этом пакете есть файл __init__.py. Откройте его через IDE. Путь к файлу выглядит так:

PYTHON
# На Windows.
директория_проекта/venv/Lib/site-packages/asciimatics/__init__.py
# На Linux/MacOS.
директория_проекта/venv/lib/python3.9/site-packages/asciimatics/__init__.py 

В начале файла есть описание модуля, заключённое в тройные кавычки:

PYTHON

"""
Asciimatics is a package to help people create full-screen text UIs (from interactive forms to
ASCII animations) on any platform.  It is licensed under the Apache Software Foundation License 2.0.
"""
    ...

Это docstring, «строка документации», в ней автор кода описывает содержимое пакета, модуля или функции; такое описание позволяет другим разработчикам понять, что делает тот или иной код, не исследуя его.

Что и как можно документировать

Строки документации принято писать для публичных функций, методов и классов. Иногда в докстринге описывают весь модуль целиком.

Вот как может выглядеть документированный код:

PYTHON
"""Документация модуля. Описывает работу классов и функций. 
Размещается в верхней части файла (начиная с первой строки).
"""

def tricky_func(self):
    """Описывает работу функции tricky_func."""
    ...

class Test:
    """Класс Test используется для демонстрации docstring. 
    После docstring в классе нужна пустая строка: методы класса должны
    отделяться от предыдущего кода одной пустой строкой."""

    def first(self):
        """Этот docstring описывает метод first и 
        демонстрирует перенос строки 
        документации.
        """
        ...
 

💡 Строки документации пишутся по определённым правилам. Соблюдение этих правил упростит чтение вашей документации и, дополнительно, создаст вам хорошую репутацию в команде. Правила оформления докстрингов описаны в стандарте PEP257.

Основные правила оформления докстрингов

После открывающих тройных кавычек """ не должно быть пробела.
Докстринг начинается с заглавной буквы и заканчивается точкой:
PYTHON
"""Возвращает число 1."""
Если докстринг не умещается в одну строку — можно разбить его на несколько строк. Отступы на новой строке должны выровнять текст по кавычкам:
PYTHON
def tricky_func(): """Можно перенести так. """ def muddy_func(): """ А можно - так. """
Если документируется класс — после строки документации оставляется пустая строка. В остальных случаях код должен начинаться сразу после докстринга.
Пакеты документируются в файле __init__.py. Докстринг должен находиться в самом начале файла. В докстринге пакета содержится:
- описание пакета;
- список модулей и пакетов, которые экспортирует описываемый модуль;
- имя автора кода;
- контактные данные;
- лицензия.

Существуют разные стили оформления строк документации. Вот самые популярные:

В учебных проектах Яндекс Практикума строгое соблюдение стиля необязательно, достаточно коротко на русском (а лучше на английском) языке описать принцип работы документируемого кода.

Главное преимущество докстрингов

По сравнению с обычными комментариями у докстрингов есть серьёзное преимущество: к ним можно обратиться программно. Например, можно вызвать в консоль докстринг импортируемой функции, не открывая файл, в котором эта функция хранится. С обычными комментариями такой номер не пройдёт.

Самый простой способ получить докстринг из какого-то объекта — использовать атрибут __doc__. Python автоматически создаёт этот атрибут для всех объектов.

Откройте в IDE пустой файл, скопируйте в него код и запустите программу:

PYTHON
import math

# Спросим, что хорошего в этой библиотеке.
print(math.__doc__)

# Будет напечатано:
# This module provides access to the mathematical functions
# defined by the C standard. 

У встроенной функции print() тоже есть докстринг. Выведите его в терминал.

Каков порядок информации в докстринге функции print()?

Описание функции, пример вызова, опциональные аргументы

Описание функции, опциональные аргументы, пример вызова функции

Опциональные аргументы, описание функции, пример вызова

Опциональные аргументы, примеры вызова функции, описание функции

Пример вызова функции, описание функции, опциональные аргументы

Всё так! Содержание информации в докстринге и последовательность верные.

Аккуратный вывод докстрингов

Строки документации можно вызвать из любого объекта, важно лишь правильно указать этот объект. Запустите код, посмотрите, как он выведет документацию для разных объектов:

КодPYTHON

 
"""Документация модуля. Описывает работу классов и функций. 
Размещается в верхней части файла (начиная с первой строки).
"""
def tricky_func(self):
    """Описывает работу функции tricky_func."""
    ...
​
​
class Test:
    """Класс Test используется для демонстрации docstring."""
​
    def first(self):
        """Описывает метод first и демонстрирует перенос строки 
        документации.
        """
        ...
​
​
print(__doc__)
print(tricky_func.__doc__)
print(Test.__doc__)
print(Test.first.__doc__)

Обратите внимание, что вторая строка докстринга метода first выводится с отступом. Выглядит как ошибка.

Избавиться от пробелов при печати многострочных докстрингов поможет метод cleandoc() из модуля inspect.

Импортируйте модуль inspect и используйте метод cleandoc(), чтобы аккуратно вывести докстринг для метода first.

КодPYTHON

 
"""Документация модуля. Описывает работу классов и функций.
Размещается в верхней части файла (начиная с первой строки).
"""
# Импортируйте модуль inspect.
import inspect
​
​
def tricky_func(self):
    """Описывает работу функции tricky_func."""
    ...
​
​
class Test:
    """Класс Test используется для демонстрации docstring."""
​
    def first(self):
        """Описывает метод first и демонстрирует перенос строки
        документации.
        """
        ...
​
​
print('Без применения cleandoc:')
print(Test.first.__doc__)
print('С применением cleandoc:')
# Выведите докстринг, используя метод cleandoc().
print(inspect.cleandoc(Test.first.__doc__))

Стиль леди и джентльменов

Документировать код необязательно, программа будет работать и без этого. Однако докстринги применяют во всех крупных проектах.

Код читают намного чаще, чем пишут, и докстринги помогают в чтении.

Докстринг — это и признак уважения, и реальная помощь коллегам, работающим с вашим кодом; это признак хорошего тона и профессионализма.